Skip to main content

Barikoi Android API SDK

License API Kotlin Version

A modern, easy-to-use Android SDK for Barikoi Location APIs. Built with Kotlin, Coroutines, and Retrofit.

Features​

11 Powerful APIs​

APIDescription
Reverse GeocodingConvert coordinates to human-readable addresses
AutocompleteSmart place suggestions as the user types
Rupantor GeocodeAdvanced free-text address formatting and geocoding
Route OverviewGet distance and duration between two points
Calculate RouteTurn-by-turn directions via GraphHopper
Route OptimizationFind the most efficient order for multiple waypoints
Place SearchFull-text search with session-based place details
Nearby PlacesFind places within a radius
Snap to RoadSnap a coordinate to the nearest road
GeofencingCheck whether a point is within a given radius

Modern Android Stack​

  • 100% Kotlin
  • Coroutines for async operations
  • Retrofit 2.11 + OkHttp 4.12 for networking
  • Moshi 1.15 for JSON parsing (KSP code-gen)
  • Type-safe sealed-class error handling

Production Ready​

  • Automatic API-key injection via OkHttp interceptor
  • Locale-safe coordinate formatting (no comma-decimal bugs)
  • Comprehensive error mapping (network, HTTP 4xx/5xx, parse, validation)
  • ProGuard / R8 consumer rules included
  • Five unit-test suites (MockWebServer)

Installation​

Step 1: Add JitPack repository​

In your root settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

Step 2: Add the dependency​

In your app's build.gradle.kts:

dependencies {
    implementation("com.github.barikoi:barikoi-api-sdk-android:1.0.0")
}

Quick Start​

Step 1 – Initialize once in Application.onCreate():

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        BarikoiClient.init(
            apiKey        = BuildConfig.BARIKOI_API_KEY,
            enableLogging = BuildConfig.DEBUG
        )
    }
}

Note: Add the MyApp class in your AndroidManifest.xml

Step 2 – Use anywhere with no key required:

class MyActivity : AppCompatActivity() {
    // Returns the same cached singleton every time
    private val barikoi = BarikoiClient()

    fun fetchAddress() {
        lifecycleScope.launch {
            barikoi.reverseGeocode(23.8103, 90.4125)
                .onSuccess { place -> Log.d("Barikoi", "Address: ${place.address}") }
                .onFailure { error -> Log.e("Barikoi", "Error: ${error.message}") }
        }
    }
}

API Reference​

Reverse Geocoding​

Convert coordinates to a human-readable address:

barikoi.reverseGeocode(
    latitude  = 23.8103,
    longitude = 90.4125,
    bangla    = true       // optional: return address in Bangla
).onSuccess { place ->
    println("Address : ${place.displayAddress}")
    println("Area    : ${place.area}")
    println("City    : ${place.city}")
    println("Post    : ${place.displayPostCode}")
}.onFailure { error ->
    println("Error: ${error.message}")
}

Autocomplete​

Get smart place suggestions:

barikoi.autocomplete(
    query  = "Gulshan",
    bangla = true
).onSuccess { places ->
    places.forEach { place ->
        println("${place.address} – ${place.area}")
    }
}

Rupantor Geocode​

Format and geocode a free-text address:

barikoi.rupantorGeocode(
    query    = "House 10, Road 5, Gulshan 1, Dhaka",
    thana    = true,
    district = true,
    bangla   = false
).onSuccess { response ->
    println("Fixed address      : ${response.fixedAddress}")
    println("Bangla address     : ${response.banglaAddress}")
    println("Confidence         : ${response.confidenceScorePercentage}%")
    println("Geocoded latitude  : ${response.geocodedAddress?.latitude}")
    println("Geocoded longitude : ${response.geocodedAddress?.longitude}")
}

Route Overview​

Get distance and duration between two points:

barikoi.routeOverview(
    startLat   = 23.8103,
    startLon   = 90.4125,
    endLat     = 23.7808,
    endLon     = 90.4217,
    profile    = "car"     // optional: car | foot | bike
).onSuccess { routes ->
    routes.firstOrNull()?.let { route ->
        println("Distance : ${route.distance} m")
        println("Duration : ${route.duration} s")
    }
}

Calculate Route​

Get detailed turn-by-turn directions via GraphHopper:

barikoi.calculateRoute(
    startLat = 23.8103,
    startLon = 90.4125,
    endLat   = 23.7808,
    endLon   = 90.4217,
    profile  = "car"
).onSuccess { response ->
    response.paths?.firstOrNull()?.let { path ->
        println("Distance : ${path.distanceInKm} km")
        println("Duration : ${path.durationInMinutes} min")
        path.instructions?.forEach { step ->
            println("  → ${step.text}")
        }
    }
}

Route Optimization​

Find the most efficient order to visit multiple waypoints:

barikoi.optimizeRoute(
    sourceLat      = 23.8103,
    sourceLon      = 90.4125,
    destinationLat = 23.7516,
    destinationLon = 90.3888,
    waypoints      = listOf(
        Pair(23.7808, 90.4217),
        Pair(23.7650, 90.4050)
    ),
    profile = "car"
).onSuccess { response ->
    response.paths?.firstOrNull()?.let { path ->
        println("Optimized distance : ${path.distanceInKm} km")
        println("Optimized duration : ${path.durationInMinutes} min")
    }
}

Place Search + Details​

Full-text search with session-based place details:

// Step 1 – search
barikoi.searchPlace("Bashundhara").onSuccess { response ->
    val sessionId  = response.sessionId           ?: return@onSuccess
    val firstPlace = response.places?.firstOrNull() ?: return@onSuccess

    // Step 2 – fetch details with the session ID
    barikoi.placeDetails(
        placeCode = firstPlace.placeCode ?: return@onSuccess,
        sessionId = sessionId
    ).onSuccess { place ->
        println("Name    : ${place.name}")
        println("Address : ${place.displayAddress}")
        println("Lat/Lon : ${place.latitude}, ${place.longitude}")
    }
}

Nearby Places​

Find places within a radius:

barikoi.nearbyPlaces(
    latitude  = 23.8103,
    longitude = 90.4125,
    radius    = 1.0,   // kilometres
    limit     = 10
).onSuccess { places ->
    places.forEach { place ->
        println("${place.address} – ${place.distanceWithinMeters} m away")
    }
}

Snap to Road​

Snap a coordinate to the nearest road:

barikoi.snapToRoad(
    latitude  = 23.8103,
    longitude = 90.4125
).onSuccess { response ->
    println("Snapped to : ${response.snappedLatitude}, ${response.snappedLongitude}")
    println("Distance   : ${response.distance} m")
}

Geofencing​

Check whether a destination is within a radius:

barikoi.checkNearby(
    currentLat     = 23.8103,
    currentLon     = 90.4125,
    destinationLat = 23.8110,
    destinationLon = 90.4130,
    radiusMeters   = 500.0
).onSuccess { response ->
    if (response.isInside) {
        println("Inside radius! Distance: ${response.distance} m")
    } else {
        println("Outside radius. Distance: ${response.distance} m")
    }
}

Error Handling​

All SDK methods return Result<T>. Errors are mapped to typed BarikoiError subclasses:

barikoi.reverseGeocode(lat, lon).onFailure { error ->
    when (error) {
        is BarikoiError.NetworkError       -> showToast("No internet connection")
        is BarikoiError.UnauthorizedError  -> showToast("Invalid or missing API key")
        is BarikoiError.QuotaExceededError -> showToast("API quota exceeded")
        is BarikoiError.RateLimitError     -> showToast("Too many requests – try again later")
        is BarikoiError.BadRequestError    -> showToast("Invalid request parameters")
        is BarikoiError.ValidationError    -> showToast("Bad input: ${error.message}")
        is BarikoiError.ParseError         -> showToast("Unexpected response format")
        is BarikoiError.HttpError          -> showToast("HTTP ${error.code}: ${error.message}")
        else                               -> showToast("Error: ${error.message}")
    }
}

Convenience helpers on BarikoiError​

PropertyDescription
isNetworkErrorConnectivity failure (no internet, timeout, DNS)
isAuthErrorHTTP 401 / 403 – invalid or missing API key
isQuotaErrorHTTP 402 – billing / quota limit exceeded
isRateLimitErrorHTTP 429 – too many requests
isValidationErrorClient-side bad input (blank query, invalid coords, etc.)
isParseErrorResponse received but could not be parsed
isNotFoundHTTP 404
isClientErrorAny 4xx or local validation error
isServerErrorAny 5xx server-side error

Configuration​

Custom timeouts​

val barikoi = BarikoiClient.Builder()
    .apiKey("YOUR_API_KEY")
    .connectTimeoutSeconds(60)
    .readTimeoutSeconds(60)
    .writeTimeoutSeconds(60)
    .build()

HTTP logging (debug only)​

val barikoi = BarikoiClient.Builder()
    .apiKey("YOUR_API_KEY")
    .enableLogging(true)   // prints full request / response bodies in Logcat
    .build()

Permissions​

Add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Requirements​

ItemVersion
Min SDKAPI 24 (Android 7.0)
Target SDKAPI 36+
Kotlin2.0.21
Coroutines1.9.0
Retrofit2.11.0
OkHttp4.12.0
Moshi1.15.1

ProGuard / R8​

Consumer ProGuard rules are bundled automatically. No extra configuration is needed.

Get Your API Key​

  1. Sign up at https://developer.barikoi.com/register
  2. Create a new API key from your dashboard
  3. Pass it to BarikoiClient.init() or BarikoiClient.Builder().apiKey()

License​

Copyright 2025 Barikoi

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Support​

ChannelLink
Emailhello@barikoi.com
Websitehttps://barikoi.com
API Docshttps://docs.barikoi.com/api

Made by Barikoi